How to create a Repeater Field with wp.template()

Learn how to create repeater fields for your WordPress settings pages with wp.template(). That is a WordPress Underscore.js JavaScript method for getting an HTML template and passing data to it. In this tutorial, I will show you how to use wp.template() to create a repeater field.

How to use wp.template()

Before we get into creating a repeater field, we should first learn how to use it. Before using it inside our JavaScript code, we need to be sure that it is already available. To make it available we need to have the file wp-includes/js/wp-util.min.js included on the page.

How to do that? Pretty easy. When enqueuing our own javascript file, we need to make that file as a dependency. I will assume that we will place our file repeater.js inside a plugin folder in assets/js/.

By placing wp-util inside the dependency array, we are making sure that WordPress will load the wp-util.min.js on the page.

Template as Script

To use wp.template() on a template, we need to have that template placed inside a script. It would probably work otherwise also, but by using the script tag, that HTML won’t be displayed on the page.

Let’s imagine that we have an unordered list ul on a page and we want to append a new list item there with dynamic text. The template could be like this:

When getting a template with wp.template(), we are passing the template slug to that function. Then wp.template() will use that slug and check for a template with ID #tmpl-slug. That is why we have the ID tmpl-template on the script tag.

When that template is compiled the function wp.template will return a function. We can then use that function to pass a data object. That data object is then used to fill the template with the dynamic data. That is why we have the {{data.text}} inside that template.

Let’s now see how to do that:

First, we are getting the template by passing template to get the template #tmpl-template. Once that one is returned, we are using the variable template as a function by passing our data object to it.

The return value will be the compiled HTML with the dynamic data inside. We can then do with that HTML what we want such as appending it to an element.

Before creating a repeater field, you might be interested in viewing how to create a simple repeater field in this video.

Creating the Repeater Field

Now that you have a simple understanding on how this works, we can move on. The code we make here can be used elsewhere but it could require a bit of refactoring, so please read with understanding.

Let’s first create our field. This field can be used however you want, but I will assume that we are working on a meta box so I am getting the field data with the function get_post_meta.

The variable $field_data will be an array that will hold values. Each value will be a new input field. Each input field will have a remove button next to it so that we can remove it.

How to create a template now? When creating a repeater field, we need to make sure that we are getting all the required HTML inside it. The repeating HTML would start from the .field-group.

Do we need to pass anything to it? I don’t think so, since we just want to display a new input field. So, how will our template look like?

Adding Field on Click

We need to attach an event to add the field to our field group. So, how do we do that? We will use jQuery to get the template and append the HTML to our field container.

That was pretty simple. But how to handle removing inputs?

Removing Fields on Click

Removing a field will be done just by removing the .field-group from the DOM. We are doing that with this code:

We are attaching this even to the document so that even when adding a new field, the newly added remove button will be triggered.

Once the remove button is clicked, we are getting the parent element, which in this case is .field-group. After that, we are just removing it.

Conclusion

Since the idea for this tutorial is to show you how to create a repeater field, I am not showing how to save such value. The value that is passed on a $_POST request is a simple array with all the data inside the $_POST. You can directly save that or validate the array first.

When working on complex examples, you would probably need to do something more on the JavaScript part. Other than that, working with wp.template is as simple as shown in this examples.

If you are interested in how to create a repeater field in WP Customizer, you can read my other article: WordPress Customizer Flexible List Control.

If you are interested to see how to work with multiple fields, you might want to read the code of my free plugin: https://wordpress.org/plugins/raise-prices-with-sales-for-woocommerce/. The files you might be interested in are here:

• Template: https://plugins.trac.wordpress.org/browser/raise-prices-with-sales-for-woocommerce/trunk/admin/partials/rps_wc-admin-prices.php
• JavaScript: https://plugins.trac.wordpress.org/browser/raise-prices-with-sales-for-woocommerce/trunk/admin/js/rps_wc-admin.js

Have you ever tried to build your own repeater field? Would you like seeing more examples of it? Be sure to let me know in the comments below:)

Become a Sponsor